lib,src,test,doc: add node:ffi module by cjihrig · Pull Request #62072 · nodejs/node

cjihrig · 2026-03-02T14:43:52Z

This is not ready for review yet. Just opening to see if this is something the project is still interested in.

nodejs-github-bot · 2026-03-02T14:43:58Z

Review requested:

@nodejs/gyp
@nodejs/security-wg

anonrig · 2026-03-02T16:00:18Z

Yes

Qard

Looks very cool! I'm glad to see someone has picked this back up. 🙂

I did a quick review and it all looks good. My only comment is there seems to be a bunch of static strings and a private symbol which we might want to define in env_properties.h.

src/node_ffi.cc

github-actions · 2026-03-18T23:43:23Z

Failed to start CI

   ⚠  No approving reviews found
   ✘  Refusing to run CI on potentially unsafe PR

https://github.com/nodejs/node/actions/runs/23272564448

nodejs-github-bot · 2026-03-18T23:44:41Z

CI: https://ci.nodejs.org/job/node-test-pull-request/71877/

nodejs-github-bot · 2026-03-18T23:54:55Z

CI: https://ci.nodejs.org/job/node-test-pull-request/71878/

cjihrig · 2026-03-18T23:59:59Z

@anonrig I cancelled that CI run to save resources. I started https://ci.nodejs.org/job/node-test-pull-request/71877/ manually, and it's currently running.

@cjihrig

given that this is still draft and @cjihrig indicated it's not ready for review, a sign off is not yet appropriate.

mcollina

lgtm

nodejs-github-bot · 2026-03-19T03:10:14Z

CI: https://ci.nodejs.org/job/node-test-pull-request/71884/

@cjihrig

given that this is still draft and @cjihrig indicated it's not ready for review, a sign off is not yet appropriate.

jasnell · 2026-03-19T03:41:32Z

@cjihrig ... definitely interested in seeing ffi land. I was hoping @bengl's prior efforts would make progress. Once you feel this is ready to go, I'll be happy to review.

mcollina

lgtm

mcollina · 2026-04-01T17:27:16Z

@cjihrig @ShogunPanda this now conflicts, can you rebase?

codecov · 2026-04-02T16:06:16Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.66%. Comparing base (e775989) to head (2587eef).
⚠️ Report is 43 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62072      +/-   ##
==========================================
- Coverage   89.71%   89.66%   -0.06%     
==========================================
  Files         695      706      +11     
  Lines      214546   217789    +3243     
  Branches    41082    41665     +583     
==========================================
+ Hits       192487   195279    +2792     
- Misses      14116    14439     +323     
- Partials     7943     8071     +128

Files with missing lines	Coverage Δ
lib/ffi.js	`95.73% <ø> (ø)`
lib/internal/bootstrap/realm.js	`96.21% <ø> (+<0.01%)`	⬆️
lib/internal/process/permission.js	`100.00% <ø> (ø)`
lib/internal/process/pre_execution.js	`98.63% <ø> (+1.40%)`	⬆️
src/env.cc	`85.30% <ø> (+0.11%)`	⬆️
src/ffi/data.cc	`78.77% <ø> (ø)`
src/ffi/types.cc	`59.67% <ø> (ø)`
src/node_binding.cc	`82.74% <ø> (ø)`
src/node_builtins.cc	`76.09% <ø> (-0.15%)`	⬇️
src/node_ffi.cc	`69.07% <ø> (ø)`
... and 8 more

... and 71 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

* src,deps,test: various improvements Signed-off-by: Paolo Insogna <paolo@cowtech.it> * deps,test: fixed failures Signed-off-by: Paolo Insogna <paolo@cowtech.it> * deps,test: fixed failures Signed-off-by: Paolo Insogna <paolo@cowtech.it> * deps,test: fixed failures Signed-off-by: Paolo Insogna <paolo@cowtech.it> * deps,test: fixed failures Signed-off-by: Paolo Insogna <paolo@cowtech.it> * doc,lib: fixed failures Signed-off-by: Paolo Insogna <paolo@cowtech.it> * deps: fixed failures Signed-off-by: Paolo Insogna <paolo@cowtech.it> * test: fixed failures Signed-off-by: Paolo Insogna <paolo@cowtech.it> --------- Signed-off-by: Paolo Insogna <paolo@cowtech.it>

* test: fixed build on Windows Signed-off-by: Paolo Insogna <paolo@cowtech.it> * test: fixed build on Windows Signed-off-by: Paolo Insogna <paolo@cowtech.it> * test: fixed build on Windows Signed-off-by: Paolo Insogna <paolo@cowtech.it> * test: fixed build on Windows Signed-off-by: Paolo Insogna <paolo@cowtech.it> * test: removed useless file Signed-off-by: Paolo Insogna <paolo@cowtech.it> --------- Signed-off-by: Paolo Insogna <paolo@cowtech.it>

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

mcollina

lgtm

nodejs-github-bot · 2026-04-06T09:21:01Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72504/

nodejs-github-bot · 2026-04-06T10:41:14Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72510/

nodejs-github-bot · 2026-04-06T14:21:19Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72517/

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

mcollina

lgtm

nodejs-github-bot · 2026-04-07T13:55:49Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72538/

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

nodejs-github-bot · 2026-04-09T09:58:22Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72578/

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

nodejs-github-bot · 2026-04-09T12:14:45Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72581/

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

nodejs-github-bot · 2026-04-09T15:12:41Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72588/

everett1992 · 2026-04-10T00:08:38Z

doc/api/ffi.md

+Other targets require building Node.js against a shared libffi with
+`--shared-ffi`. The unofficial GN build does not support `node:ffi`.
+
+When using the [Permission Model][], FFI APIs are


Should permissions have an option to restrict which files or symbols can be loaded?

I don't think so, it could potentially be a very long list.
Anyway, I'm open to reconsider this in a future PR, but I think we can start with this as a starting point.

everett1992 · 2026-04-10T00:09:43Z

doc/api/ffi.md

+Supported type names:
+
+* `void`
+* `i8`, `int8`


Why introduce any aliases? Seems like extra mental overhead to remember that there's two ways to spell the same thing?

Should we export a constant with available types?

About the first question: it's to make transition smooth from other languages or runtime. You don't have to remember both, you just use what you already know.

About the second: that's a good suggestion. I will add it!

IMO while aliases make writing code easier and more familiar (you write what you're familiar with), they make reading code harder, especially when you read other peoples code (you're reading their conventions and checking when they mean the same thing and when they mean different).

I think good docs, @types/node, and the constant we add will help the writing UX with fewer downsides.

Adding aliases would be backward compatible, but removing them would not, so I'd prefer starting with no aliases.
(I'm just another community member that wants to see node:ffi land, not a required reviewer)

everett1992 · 2026-04-10T01:31:47Z

doc/api/ffi.md

+through reentrant JavaScript such as FFI callbacks. Doing so may crash the
+process, produce incorrect output, or corrupt memory.
+
+The `char` type follows the platform C ABI. On platforms where plain C `char`


Include an example (or function) to check the platform c abi?

I think this is unnecessary. First of all, this is transparent to node:ffi so users won't really care about this. The few that might care probably know which platforms they're developing on.

This and the request for a suffix helper are intended for code that doesn't know what platforms it will run on - I think developers would write similar code to map platform to C ABI or dll suffix which seems like a good opportunity for a built in helper.

everett1992 · 2026-04-10T01:33:38Z

doc/api/ffi.md

+
+Supported fields:
+
+* `result`, `return`, or `returns` for the return type.


Is there an explanation why there's more than one way to spell this? Compat with other ffi libraries? If so, we should document that, tho I'd rather pick one or drop compat goals.

See above: no need to, just trying to use the principle of least surprise here. Other runtimes use different conventions so I'm trying to please anybody, since there is no hard requirement on the ABI side.

everett1992 · 2026-04-10T02:06:54Z

test/ffi/ffi-test-common.js

+);
+const libraryPath = path.join(
+  fixtureBuildDir,
+  process.platform === 'win32' ? 'ffi_test_library.dll' :


Should node:ffi export a suffix constant?

I don't think so. This is just used in tests, I guess people know which file they are loading :)

everett1992 · 2026-04-10T02:11:11Z

lib/internal/process/pre_execution.js

@@ -706,7 +719,7 @@ function initializePermission() {
    const { availableFlags } = require('internal/process/permission');
    ArrayPrototypeForEach(availableFlags(), (flag) => {
      const value = getOptionValue(flag);
-      if (value.length) {
+      if (value === true || value?.length) {


Why is this change required? There's already boolean permission flags

everett1992 · 2026-04-10T02:29:29Z

doc/api/ffi.md

+offset, or writing through a stale pointer can corrupt memory or crash the
+process.
+
+## `ffi.toString(pointer)`


Should this have an optional max length?

I'm not sure to be honest. The underlying C++ method will return an empty string, if length>maxLength, which I find counter-intuitive.
I wouldn't for now, but we can eventually change in a follow up PR.

nodejs-github-bot added build Issues and PRs related to build files or the CI. dependencies Pull requests that update a dependency file. needs-ci PRs that need a full CI run. labels Mar 2, 2026

Qard reviewed Mar 2, 2026

View reviewed changes

src/node_ffi.cc Outdated Show resolved Hide resolved

cjihrig force-pushed the ffi branch 2 times, most recently from 9462e4d to 631d73a Compare March 10, 2026 03:46

cjihrig added the request-ci Add this label to start a Jenkins CI on a PR. label Mar 18, 2026

github-actions bot added request-ci-failed An error occurred while starting CI via request-ci label, and manual interventon is needed. and removed request-ci Add this label to start a Jenkins CI on a PR. labels Mar 18, 2026

anonrig previously approved these changes Mar 18, 2026

View reviewed changes

anonrig added request-ci Add this label to start a Jenkins CI on a PR. and removed request-ci-failed An error occurred while starting CI via request-ci label, and manual interventon is needed. labels Mar 18, 2026

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Mar 18, 2026

mcollina previously approved these changes Mar 19, 2026

View reviewed changes

mcollina added request-ci Add this label to start a Jenkins CI on a PR. and removed request-ci Add this label to start a Jenkins CI on a PR. labels Mar 19, 2026

cjihrig marked this pull request as ready for review April 1, 2026 14:41

mcollina approved these changes Apr 1, 2026

View reviewed changes

cjihrig and others added 6 commits April 6, 2026 08:12

tests

2ad47ef

src: formatted files

c44780a

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

fixup

769be84

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

fixup

e04304c

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

ShogunPanda force-pushed the ffi branch from d562ab9 to e04304c Compare April 6, 2026 06:16

ShogunPanda added the request-ci Add this label to start a Jenkins CI on a PR. label Apr 6, 2026

mcollina approved these changes Apr 6, 2026

View reviewed changes

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Apr 6, 2026

test: fixed failures

a032ade

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

ShogunPanda added the request-ci Add this label to start a Jenkins CI on a PR. label Apr 7, 2026

src: formatted files

633528a

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

mcollina approved these changes Apr 7, 2026

View reviewed changes

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Apr 7, 2026

src: fix arguments handling

35d65ee

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

ShogunPanda added the request-ci Add this label to start a Jenkins CI on a PR. label Apr 9, 2026

test: formatted files

be31bc6

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

test: fix test library

1a94b94

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

deps: fix build on Windows

2587eef

Signed-off-by: Paolo Insogna <paolo@cowtech.it>

everett1992 reviewed Apr 10, 2026

View reviewed changes

simonklee mentioned this pull request Apr 10, 2026

Node.js support anomalyco/opentui#939

Open

justjake mentioned this pull request Apr 10, 2026

koffi vNext release? Koromix/koffi#263

Open


		Supported fields:

		* `result`, `return`, or `returns` for the return type.

Uh oh!

Conversation

cjihrig commented Mar 2, 2026

Uh oh!

nodejs-github-bot commented Mar 2, 2026

Uh oh!

anonrig commented Mar 2, 2026

Uh oh!

Qard left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Mar 18, 2026

Uh oh!

nodejs-github-bot commented Mar 18, 2026

Uh oh!

nodejs-github-bot commented Mar 18, 2026

Uh oh!

cjihrig commented Mar 18, 2026

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Mar 19, 2026

Uh oh!

jasnell commented Mar 19, 2026

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

mcollina commented Apr 1, 2026

Uh oh!

codecov bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Apr 6, 2026

Uh oh!

nodejs-github-bot commented Apr 6, 2026

Uh oh!

nodejs-github-bot commented Apr 6, 2026

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Apr 7, 2026

Uh oh!

nodejs-github-bot commented Apr 9, 2026

Uh oh!

nodejs-github-bot commented Apr 9, 2026

Uh oh!

nodejs-github-bot commented Apr 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Apr 2, 2026 •

edited

Loading